Release 10.1A: OpenEdge Development:
Programming Interfaces

Custom audit configuration tools

OpenEdge provides core support for managing audit policies (rules) that govern how audit trails are defined, tracked, and recorded. The Audit Policy Maintenance tool provided with OpenEdge allows you to:

Create, delete, and configure audit policies.
Create audit policy templates to simplify initial audit configuration.
Import and export audit policies in order to apply them to multiple databases.
Define application events generated in your applications.

For more information on configuring audit policies using Audit Policy Management, see OpenEdge Getting Started: Core Business Services and the online help for the Audit Policy Maintenance tool.

Accessing the audit policy tables

You can write your own tools to perform same functions supported by the Audit Policy Maintenance tool. To do so, you must:

Write the 4GL code to query and update audit policy tables in a given audit-enabled database.
Use methods of the AUDIT-POLICY system handle to manage the effect of any changes to existing auditing policy settings.

The following tables store the basic audit policy settings for an audit-enabled database:

_aud-event — Defines the supported audit events. Each OpenEdge-defined event has a unique event ID (_Event-id field value) with a value less than 32000. All application-defined events must also have a unique event ID with a value of 32000 or greater.
_aud-audit-policy — Provides a mechanism to define named audit policies configured according to different policy requirements.
_aud-event-policy — Defines policy settings for audit events of a specific named audit policy, and specifies such information as if the audit event is enabled and the level of audit detail to be recorded.
_aud-field-policy — Optionally, defines any field-level policy settings for a specific named audit policy. Fields without settings inherit any settings for the table, if any, and are disabled from auditing otherwise.
_aud-file-policy — Optionally, defines any table-level policy settings for a specific named audit policy. Tables without settings are disabled from auditing.

In addition to these principle audit policy tables, the following tables provide information about auditing and security features of a given OpenEdge RDBMS. You do not typically change these tables for Audit Policy Maintenance activities, but they might be useful for reference purposes:

_db — Provides standard metaschema information in an OpenEdge RDBMS, including a global unique identifier (GUID) that is used to uniquely identify the database in audit data aggregated from multiple databases.
_db-option — Provides an extensible means to define criteria for handling various database management options, including auditing and security. OpenEdge provides such options for managing auditing and general database security identities and permissions.
_db-detail — Stores auditing-specific information about a database, including the message authentication code (MAC) key used to secure and seal audit data, depending on the audit data security level (an audit policy setting).

For more information on these tables, see the sections on audit policies and data in OpenEdge Getting Started: Core Business Services .

In order to allow audit policy changes to occur without taking an audit-enabled database off line, the 4GL provides a mechanism to inform the database server that audit policy changes have occurred so it can refresh its audit policy settings. You can do this using the REFRESH-AUDIT-POLICY( ) method on the AUDIT-POLICY system handle. By invoking this method for a specified database, the OpenEdge RDBMS can immediately use the latest changes to audit policies in order to process and record audit events.

Accessing the Audit Policy Maintenance APIs

The rules for configuring and managing audit policies directly in the audit policy tables are complex. As an aid to following these rules, OpenEdge provides a set of Audit Policy Maintenance APIs that you can use to properly manage these tables. These APIs rely on standard data definitions for 4GL temp-tables and ProDataSets that are used as intermediate audit policy storage. They also support remote client access to API services hosted on an AppServer.

OpenEdge uses these APIs to implement the Audit Policy Maintenance tool, and the source code for the tool is installed with OpenEdge. You can thus use this tool as a working sample application for writing your own audit policy configuration tools. You can find all the source code for the APIs, including the Audit Policy Maintenance main procedure (_apmt.p) in the following OpenEdge installation directory:

OpenEdge_install_dir\src\auditing

For a description of the individual API procedure files, see Appendix B "Audit Policy Maintenance APIs."

Audit configuration security

When accessing the audit policy tables directly or through the Audit Policy Maintenance APIs, the user must have the Audit Administrator privilege in order to create, read, update, and delete audit policy records. To query the audit policy tables, the user only requires the Audit Data Reporter privilege.